package com.study.map.service;

import com.study.map.dto.GeoRequest;
import com.study.map.dto.GeoResponse;
import com.study.map.exception.MapServiceException;

/**
 * 地理编码服务接口
 * 提供地址与经纬度坐标相互转换的功能
 *
 * @author study
 * @date 2025-08-31
 */
public interface IGeoService {

    /**
     * 地理编码：将地址转换为经纬度坐标
     *
     * @param request 地理编码请求参数
     * @return 地理编码结果
     * @throws MapServiceException 地图服务异常
     */
    GeoResponse geoCode(GeoRequest request) throws MapServiceException;

    /**
     * 地理编码：将地址转换为经纬度坐标
     *
     * @param address 地址
     * @return 地理编码结果
     * @throws MapServiceException 地图服务异常
     */
    GeoResponse geoCode(String address) throws MapServiceException;

    /**
     * 地理编码：将地址转换为经纬度坐标
     *
     * @param address 地址
     * @param city 城市
     * @return 地理编码结果
     * @throws MapServiceException 地图服务异常
     */
    GeoResponse geoCode(String address, String city) throws MapServiceException;
}